Skip to content

feat(node): send Nodemailer mail through PostHog - #5575

Closed
Silthus wants to merge 12 commits into
emails-v2/node-integration-optionfrom
emails-v2/node-nodemailer-transport
Closed

Silthus wants to merge 12 commits into
emails-v2/node-integration-optionfrom
emails-v2/node-nodemailer-transport

Conversation

@Silthus

@Silthus Silthus commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem

A Node app that sends email with Nodemailer can't send that email through PostHog without rewriting every sendMail call as posthog.emails.send().

Ticket: https://github.com/PostHog/michaelr-context/issues/41 (private).

Stacked on #5574, which is stacked on #5514. Merge them first. This PR stays a draft until the email SDKs release.

Seams for review. The integration option from #5574 is a seam: the Convex sender in #5579 stacks on it too, and PostHog/posthog#130017 reads the name before the / of a valid X-PostHog-Integration header as the send's client. The posthog.com page for the transport is PostHog/posthog.com#21987. Check for cross-stack breaks: a marker pattern that the server reads differently, the same concept built twice, or a header that one stack sets and another doesn't read.

Impact

Shows on the client property that PostHog/posthog#130017 adds to the transactional email api send event: weekly organizations whose code sends come from nodemailer. Success: Nodemailer sends appear there after the email SDKs release, from teams that already send with Nodemailer.

Merge danger

Warning

🟡 Merge risk: medium, 🔴 at release · one-way door once posthog-node releases: the posthog-node/nodemailer entry point, its posthog options and its refusal codes

  • New entry point: a Nodemailer app that imports posthog-node/nodemailer sends each message as one emails.send(), or gets an EPOSTHOGUNSUPPORTED refusal before any request. The merge lands on a stack branch and no released package carries it, so no traffic takes it until the release; the grade is medium because the diff adds more than 400 production lines while a row stays uncovered.
  • Everyone who doesn't import it is unchanged: posthog-node still loads and sends without Nodemailer installed (nodemailer-absent.spec.ts on the built package), and the SDK's own send path changes only by the isRetryable export.
  • Uncovered at release: a send through real PostHog. The tests run real Nodemailer and the real SDK against a stubbed fetch and FakePostHog; a mapping bug they miss would send other content than the app asked for, without an error, to the Nodemailer teams that opt in.
  • Reads before the send: the transport reads each message whole through Nodemailer's normalize(), as Nodemailer's JSON and SES transports do, before the SDK's 10-file and 40 MB check. A stalled stream of the app's fails with ETIMEDOUT after 60 seconds and is closed; a URL ends within Nodemailer's own fetch limits.
  • Switch-off: none: an opt-in import, live for a caller once a release carries it. Fix forward.
  • Tier: critical (c: one-way door once posthog-node releases posthog-node/nodemailer)

Rollout

Changes

import nodemailer from 'nodemailer'
import { createPostHogTransport } from 'posthog-node/nodemailer'

const transporter = nodemailer.createTransport(createPostHogTransport({ client: posthog }))
await transporter.sendMail({ from, to, subject, html, posthog: { template_key: 'order-shipped', idempotency_key } })
  • createPostHogTransport({ client, defaultTemplateKey? }) returns a Nodemailer transport, { name, version, send(mail, done) }. It reads each message with mail.normalize(), within 60 seconds, or fails with ETIMEDOUT. It doesn't import Nodemailer at run time, so posthog-node and posthog-node/nodemailer load when Nodemailer isn't installed.
  • Each message becomes one content-from-code emails.send(), with integration: 'nodemailer/<posthog-node version>' (from feat(node): let an integration name itself on an email send #5574). The SDK still does the checks, the uploads, the request, the retries, and the idempotency key. Attachments, inline images, and data URL images go through the SDK's upload. The content IDs Nodemailer generates for data URL images are renumbered in order, skipping any the message sets itself, so a retry maps to the same send. Only whole cid: references change, so a longer content ID that starts with a generated one keeps its name, and a reference in a srcset or a CSS url(&quot;…&quot;) changes too.
  • PostHog's options for one message go in sendMail({ posthog: { distinct_id, template_key, idempotency_key, tracking, sensitive } }). tracking takes true, false, or { opens, clicks }, and sensitive passes through; there is no capture_engagement. In TypeScript, the entry point adds posthog to Nodemailer's message options, in CommonJS and in NodeNext ESM consumers. The template key is posthog.template_key, then defaultTemplateKey, then nodemailer.
  • A message PostHog can't send fails before any request with an Error that has code: 'EPOSTHOGUNSUPPORTED' and a refusal: multiple_to, unsupported_header, unsupported_part, unsupported_priority, unsupported_option, envelope_mismatch, inline_without_cid, or invalid_template_key. That covers headers and parts PostHog doesn't send, raw MIME, an envelope of the message's own that names other people, a registered stream plugin or DKIM, and any message option the transport doesn't know. PostHog never sends part of a message.
  • A failed send fails with an Error that has code, status, detail, attr, retryable, and retry_after (seconds), with the SDK's EmailError as its cause. It is retryable only when the message has posthog.idempotency_key and the SDK would retry the failure: without a key, an earlier attempt may have queued the message, so a retry could send a second copy. isRetryable is now exported inside the package for this.
  • Success calls done(null, { messageId }) with PostHog's message ID.

Evidence

  • Lane gate on 4cf1529 (references, oxfmt, oxlint, package lint, typecheck, build, vitest run for posthog-node): green, 54 files, 1882 tests. It ran through fleet heavy on the devbox because the worktree box didn't start. CI on this PR: see below, because the base isn't main.
  • Red, then green: each review fix has a test that failed before it, and a mutation that reverts the fix fails that test.
  • Test seams: a real nodemailer.createTransport(createPostHogTransport(...)) and sendMail(), through the real SDK, with fetch stubbed, and with FakePostHog for files.
    • Shared conformance cases for email adapters: each case that applies to Nodemailer checks the exact request body and the X-PostHog-Integration and User-Agent headers. That is every rendered send, display names, cc, bcc and reply-to, the posthog options with tracking and sensitive, the default template key, the ignored headers, and an envelope that names the same people.
    • Each refusal, with no request: the conformance refusal cases, plus AMP, iCalendar, watchHtml, alternatives, raw MIME on the message, the HTML or an attachment, headers on the HTML, text or an attachment, a high priority, inReplyTo, list, otp, a sender that isn't from, REQUIRETLS, DKIM, an unknown option, and stream plugins that transform, process, or set a header.
    • Attachments through FakePostHog: case 04 with an inline image, a text file and a stream, and a retry of a message with data URL images that replays, a data URL image next to an image whose content ID the message sets to the same name the renumbering would pick, a longer content ID that starts with a generated one, and generated references in a srcset and a CSS url(&quot;…&quot;).
    • The error map: 400, 401, 403, 404, 409, 422, 429 for quota and for throttling (with Retry-After), 500, 503, and a network error, with an idempotency key, and the failures the SDK retries without one, which say retryable: false.
    • A message without from that has a reply-to sends, from the project's default sender. A stalled attachment stream fails with ETIMEDOUT and is closed.
  • nodemailer-absent.spec.ts loads the built posthog-node and posthog-node/nodemailer through import and require, with nodemailer unresolvable, and sends one message. nodemailer-process.spec.ts runs a script on the built package with a stalled attachment and checks the script keeps running once the send has started, until the send fails.
  • Type tests: types/nodemailer-transport.ts checks createTransport(createPostHogTransport(...)), sendMail({ posthog }), and info.messageId, and rejects an unknown or wrongly typed posthog option. nodemailer-declarations.spec.ts compiles NodeNext .mts and .cts consumers against the built declarations.
  • Cross-version proof (saved in the proof store): a message sent through this transport on the built package carries X-PostHog-Integration: nodemailer/<version>, which _sending_client from feat(messaging): record the sending client on transactional email sends posthog#130017 reads as nodemailer. Today's server is checked by a code search only: posthog master has no reader for the header. The launch train's live send against production sends this request to today's server.
  • Live run: gap. Live sends for this stack run in one launch train that the map's conductor runs, against this branch's head.

Spec divergence. The emails spec in sdk-specs doesn't define framework adapters. This entry point uses only emails.send() and the integration option from #5574. Against the shared adapter contract, it adds the unsupported_option refusal, and it maps open and click controls to tracking instead of capture_engagement.

Release info Sub-libraries affected

Libraries affected

  • posthog-node

Checklist

  • All commits are signed (see Commit signing)
  • Tests for new code
  • Accounted for the impact of any changes across different platforms
  • Accounted for backwards compatibility of any changes (no breaking changes!)
  • Took care not to unnecessarily increase the bundle size

If releasing new changes

  • Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Built by Claude Code (Opus 5.5) test-first in an earlier #41 thread, and continued in place by its successor thread, which kept the commits and their authorship. A GPT-6.1 Sol design pass found one simplification: the mapper throws the refusal error itself, with no separate refusal type.

Question Answer Who Where
How do open and click controls map? To tracking.opens and tracking.clicks, with sensitive passed through, never capture_engagement alongside them 👤 Human ticket
How do attachments travel? Through the SDK's upload 👤 Human ticket
Is category in scope? No 👤 Human ticket
Who runs the live sends? The map conductor's single launch train, not each PR 👤 Human ticket
Where do PostHog's options go? One posthog key in sendMail(), not X-PostHog-* headers, which the transport refuses 👍 Accepted default ticket
What about a sender other than from? Refused as unsupported_header, because Nodemailer doesn't put it in the envelope and PostHog can't send it 👍 Accepted default ticket
What does success return? { messageId } only 👍 Accepted default ticket
How does TypeScript accept posthog? A module augmentation of Nodemailer's message options, with an ESM copy for NodeNext consumers 👍 Accepted default ticket
Does the README change? No, the guide is a posthog.com page 👍 Accepted default ticket
What does a registered stream plugin do? The message is refused as unsupported_option 🤖 Agent comment
When is a failed send retryable? Only with posthog.idempotency_key and when the SDK would retry; never without a key, upload network errors included 🤖 Agent comment
Is the 60-second read deadline configurable? No, documented with its ETIMEDOUT 🤖 Agent comment
How does a retry with data URL images replay? Nodemailer's generated content IDs are renumbered in order, skipping the message's own, and only whole references change 🤖 Agent comment
Does the transport undo data URL images Nodemailer adds to a reused attachments array? No: Nodemailer's mutation, which SMTP resends too; the retry fails visibly and sends nothing twice 🤖 Agent comment
Is attachment size checked while reading? No, read whole through normalize() like Nodemailer's JSON and SES transports; the SDK refuses an oversized message after the read and before any request 🤖 Agent comment
Does the transport cancel Nodemailer's reads after ETIMEDOUT? Only through Nodemailer: its Mailer closes the app's streams on the failure, and its fetch ends a URL within its own time and size limits; the transport can't reach the file and URL streams without reimplementing normalize() 🤖 Agent comment
Nodemailer's own Transport types? No, the transport types only the slice it reads 🤖 Agent comment

Involvement: 0 grilling rounds, 1 design pass (GPT-6.1 Sol), 2 review panel rounds (fresh eyes on Claude; correctness, risk, design, anti-overengineering, sweep, and the Michael and SDK spec conformance perspectives on GPT-6.1 Sol; round 2 on the fixed lenses), 3 final reads (GPT-6.1 Sol), the PostHog Review bot's threads answered, red/green and cross-version proof captured.

🤖 Generated with Claude Code

The posthog-node/nodemailer entry point exports createPostHogTransport({ client, defaultTemplateKey }). Pass it to nodemailer.createTransport() and every sendMail call sends one PostHog email through the client's emails.send, marked nodemailer/<version>. PostHog's options ride in sendMail({ posthog: { ... } }). A message PostHog can't carry fails with code EPOSTHOGUNSUPPORTED before any request, and a failed send says whether a retry with the same idempotency key can succeed. Nodemailer stays a dev dependency.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Silthus Silthus self-assigned this Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Coherence

📄 0 spec file errors · ⛔ 0 broken rules · 🚪 2 unchecked inputs · 🐛 0 bugs that came back

What is Coherence?

Coherence compares the code with its spec files (*.spec.md). A spec file lists the rules for one part of the code.

This check read 44 parts of the code and 7 rules.

Note

These findings do not make this check fail.

None of these findings are in files that this pull request changes. You do not need to fix them in this pull request.

🚪 Unchecked inputs (2)

  • public api in packages/web/Web.spec.md. The input comes from: host-app.
  • webpack plugin in packages/webpack-plugin/Webpack-plugin.spec.md. The input comes from: build.
What this means and how to fix it

Input from outside this code comes in at these places. The spec does not say what checks that input. 10 more places were already like this when Coherence was added. This list does not show them.

To close one of these, find the place by its name in the ## entrances section of its spec file. Add one line under it:

  • If all of the input goes through one function that a rule in the spec protects, add guard: <function>.
  • If a rule in the spec already checks input from the same source, add the place's name to the entrances: line of that rule.
  • If the input needs no check, add control: none - <reason>.

To get the line to add, run npx --no -- coherence scaffold control "<name>".

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed d1d5353: 6 Should fix, 1 Consider.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Comment thread packages/node/package.json Resolved
Comment thread packages/node/src/nodemailer/types.ts Resolved
Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Comment thread packages/node/src/nodemailer/mapper.ts Resolved
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Node SDK acceptance v2

Commit: 4cf1529
Workflow run and artifacts

Capture v0

✅ 83 passed / ❌ 4 non-passing / ⚠️ 954 not selected

Drill-down: run artifacts → node-v2-v0 → acceptance/report.json.diagnostics.json (match case_id below).

❌ server_snapshot_payload_false — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:
❌ server_snapshot_payload_zero — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:
❌ server_snapshot_payload_null — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:
❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertion

Flags field differs

Code: flag_request_field

Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134

the first flags request field "geoip_disable" should equal JSON false

Operation: /flags/

Field: geoip_disable

Expected:

false

Actual value:

true

Harness exit: 1; report validation exit: 1.

Capture v1

✅ 148 passed / ❌ 4 non-passing / ⚠️ 889 not selected

Drill-down: run artifacts → node-v2-v1 → acceptance/report.json.diagnostics.json (match case_id below).

❌ server_snapshot_payload_false — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:
❌ server_snapshot_payload_zero — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:
❌ server_snapshot_payload_null — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:
❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertion

Flags field differs

Code: flag_request_field

Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134

the first flags request field "geoip_disable" should equal JSON false

Operation: /flags/

Field: geoip_disable

Expected:

false

Actual value:

true

Harness exit: 1; report validation exit: 1.

Silthus and others added 3 commits November 5, 2026 12:53
…ransport for createTransport

An attachment's raw source and an attachment's own headers are refused, so PostHog never sends other bytes or loses a Content-ID. Headers passed as a list of { key, value } are read by name. The transport's normalize data is unknown to TypeScript, so createTransport() picks the transport overload and a send resolves to { messageId }. Base64 attachment content from normalize() goes to the SDK as it is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed bdca8bb: 1 Must fix, 5 Should fix.

Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Comment thread packages/node/src/nodemailer/mapper.ts Resolved
Silthus and others added 3 commits November 13, 2026 04:37
# Conflicts:
#	packages/node/package.json
#	pnpm-lock.yaml
… tracking through

Refuse every message option the transport doesn't carry, rather than a list of known ones: Nodemailer's
OTP-Token header, REQUIRETLS, DKIM, and MIME changes from stream plugins now fail with
EPOSTHOGUNSUPPORTED instead of sending without them. Compare envelope mailboxes by their exact local
part, refuse a raw HTML or text source, refuse Content-* headers PostHog doesn't set itself, send a
missing subject as an empty one, and give up on a message whose streams stall.

The posthog slot takes tracking and sensitive in place of capture_engagement, and NodeNext ESM
consumers get the slot's types too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

SDK performance: posthog-node

Benchmarks completed. No changes flagged for review.

Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.

View all results
Test Measurement Before PR With PR Change Assessment
Capture and deliver events (32-byte payload, burst)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (32-byte payload, steady)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Queue an event (32-byte payload)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Queue an event (4,096-byte payload)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate all 10 flags
Shard: flags-scaling
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate all 100 flags
Shard: flags-scaling
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate all 1,000 flags
Shard: flags-scaling
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate one boolean flag
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a cohort-filtered flag
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a flag (early match)
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a flag (late match)
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a flag (no match)
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a property-filtered flag
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a regex-filtered flag
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a rollout flag
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Evaluate a multivariate flag
Shard: flags-single
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ V8 samples do not expose total allocation count; sample count is not object count.​; head:​ V8 samples do not expose total allocation count; sample count is not object count.​
Capture and deliver events (32-byte payload, burst)
Shard: capture
Allocated memory per operation (estimated) 10.22 KiB/op 9.91 KiB/op 3% less memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Time per operation 17.25 µs/op 17.47 µs/op 1.2% more time Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Idle process memory (RSS) 102.49 MiB 102.43 MiB <0.1% less memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Observed peak process memory (RSS) 106.17 MiB 106.36 MiB 0.2% more memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Managed heap after settling 10.08 MiB 10.08 MiB <0.1% less memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Process memory after settling (RSS) 105.85 MiB 106.1 MiB 0.2% more memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Process CPU time per operation 30.39 µs/op 30.66 µs/op 0.9% more time Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Lifetime peak process memory (RSS) 106.37 MiB 106.56 MiB 0.2% more memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Allocated memory per operation (estimated) 18.1 KiB/op 17.46 KiB/op 3.5% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Time per operation 30.56 µs/op 29.84 µs/op 2.4% less time Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Idle process memory (RSS) 102.47 MiB 102.33 MiB 0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Observed peak process memory (RSS) 113.79 MiB 114 MiB 0.2% more memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Managed heap after settling 10.09 MiB 10.09 MiB <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Process memory after settling (RSS) 109.69 MiB 109.92 MiB 0.2% more memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Process CPU time per operation 43.94 µs/op 42.78 µs/op 2.6% less time Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Lifetime peak process memory (RSS) 116.08 MiB 116.33 MiB 0.2% more memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Allocated memory per operation (estimated) 10.08 KiB/op 10.41 KiB/op 3.3% more memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Time per operation 17.66 µs/op 17.6 µs/op 0.4% less time Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Idle process memory (RSS) 102.56 MiB 102.56 MiB No observed change Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Observed peak process memory (RSS) 106.96 MiB 106.64 MiB 0.3% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Managed heap after settling 10.16 MiB 10.16 MiB <0.1% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Process memory after settling (RSS) 106.89 MiB 106.7 MiB 0.2% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Process CPU time per operation 30.64 µs/op 30.49 µs/op 0.5% less time Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Lifetime peak process memory (RSS) 107 MiB 107 MiB <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Allocated memory per operation (estimated) 18.73 KiB/op 18.37 KiB/op 2% less memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Time per operation 26.54 µs/op 25.54 µs/op 3.8% less time Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Idle process memory (RSS) 102.95 MiB 102.89 MiB <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Observed peak process memory (RSS) 109.3 MiB 109.32 MiB <0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Managed heap after settling 10.17 MiB 10.17 MiB <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Process memory after settling (RSS) 108.15 MiB 107.98 MiB 0.2% less memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Process CPU time per operation 39.28 µs/op 39.23 µs/op 0.1% less time Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Lifetime peak process memory (RSS) 109.37 MiB 109.37 MiB <0.1% more memory Not flagged
Queue an event (32-byte payload)
Shard: capture
Allocated memory per operation (estimated) 8.38 KiB/op 8.62 KiB/op 2.9% more memory Not flagged
Queue an event (32-byte payload)
Shard: capture
Time per operation 11.72 µs/op 11.45 µs/op 2.3% less time Not flagged
Queue an event (32-byte payload)
Shard: capture
Process CPU time per operation 22.36 µs/op 21.87 µs/op 2.2% less time Not flagged
Queue an event (4,096-byte payload)
Shard: capture
Allocated memory per operation (estimated) 8.74 KiB/op 8.62 KiB/op 1.3% less memory Not flagged
Queue an event (4,096-byte payload)
Shard: capture
Time per operation 11.91 µs/op 12.05 µs/op 1.2% more time Not flagged
Queue an event (4,096-byte payload)
Shard: capture
Process CPU time per operation 22.27 µs/op 23.2 µs/op 4.2% more time Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Allocated memory per operation (estimated) 133.27 KiB/op 132.85 KiB/op 0.3% less memory Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Time per operation 126.56 µs/op 127.25 µs/op 0.5% more time Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Process CPU time per operation 229.67 µs/op 232.28 µs/op 1.1% more time Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Allocated memory per operation (estimated) 1.21 MiB/op 1.24 MiB/op 1.9% more memory Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Time per operation 1.03 ms/op 1.05 ms/op 1.5% more time Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Process CPU time per operation 1.81 ms/op 1.82 ms/op 0.7% more time Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Allocated memory per operation (estimated) 12.16 MiB/op 12.15 MiB/op <0.1% less memory Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Time per operation 11.64 ms/op 11.76 ms/op 1.1% more time Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Process CPU time per operation 18.58 ms/op 18.67 ms/op 0.5% more time Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Idle process memory (RSS) 286.39 MiB 286.49 MiB <0.1% more memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Observed peak process memory (RSS) 296.34 MiB 296.52 MiB <0.1% more memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Managed heap after settling 9.71 MiB 9.71 MiB <0.1% less memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Process memory after settling (RSS) 296.34 MiB 296.52 MiB <0.1% more memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Lifetime peak process memory (RSS) 296.34 MiB 296.77 MiB 0.1% more memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Idle process memory (RSS) 226.63 MiB 227.88 MiB 0.6% more memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Observed peak process memory (RSS) 239.21 MiB 240.57 MiB 0.6% more memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Managed heap after settling 11.74 MiB 11.73 MiB <0.1% less memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Process memory after settling (RSS) 234.69 MiB 235.09 MiB 0.2% more memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Lifetime peak process memory (RSS) 241.19 MiB 241.44 MiB 0.1% more memory Not flagged
Evaluate one boolean flag
Shard: flags-single
Allocated memory per operation (estimated) 17.22 KiB/op 17.18 KiB/op 0.2% less memory Not flagged
Evaluate one boolean flag
Shard: flags-single
Time per operation 49.99 µs/op 50.55 µs/op 1.1% more time Not flagged
Evaluate one boolean flag
Shard: flags-single
Process CPU time per operation 54.41 µs/op 55.76 µs/op 2.5% more time Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Allocated memory per operation (estimated) 14.27 KiB/op 14.27 KiB/op <0.1% more memory Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Time per operation 28.99 µs/op 28.66 µs/op 1.1% less time Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Process CPU time per operation 35.87 µs/op 35.28 µs/op 1.6% less time Not flagged
Evaluate a flag (early match)
Shard: flags-single
Allocated memory per operation (estimated) 17.49 KiB/op 17.63 KiB/op 0.8% more memory Not flagged
Evaluate a flag (early match)
Shard: flags-single
Time per operation 28.77 µs/op 28.43 µs/op 1.2% less time Not flagged
Evaluate a flag (early match)
Shard: flags-single
Process CPU time per operation 34.5 µs/op 34.26 µs/op 0.7% less time Not flagged
Evaluate a flag (late match)
Shard: flags-single
Allocated memory per operation (estimated) 22.29 KiB/op 22.41 KiB/op 0.5% more memory Not flagged
Evaluate a flag (late match)
Shard: flags-single
Time per operation 28.75 µs/op 29.47 µs/op 2.5% more time Not flagged
Evaluate a flag (late match)
Shard: flags-single
Process CPU time per operation 33.94 µs/op 35.13 µs/op 3.5% more time Not flagged
Evaluate a flag (no match)
Shard: flags-single
Allocated memory per operation (estimated) 16.95 KiB/op 16.98 KiB/op 0.2% more memory Not flagged
Evaluate a flag (no match)
Shard: flags-single
Time per operation 4.24 µs/op 4.32 µs/op 2% more time Not flagged
Evaluate a flag (no match)
Shard: flags-single
Process CPU time per operation 7.71 µs/op 7.93 µs/op 2.8% more time Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Allocated memory per operation (estimated) 12.76 KiB/op 12.72 KiB/op 0.3% less memory Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Time per operation 27.4 µs/op 27.67 µs/op 1% more time Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Process CPU time per operation 32.39 µs/op 32.82 µs/op 1.3% more time Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Allocated memory per operation (estimated) 18.22 KiB/op 18.3 KiB/op 0.5% more memory Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Time per operation 53.92 µs/op 54.16 µs/op 0.4% more time Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Process CPU time per operation 60.21 µs/op 60.45 µs/op 0.4% more time Not flagged
Evaluate a rollout flag
Shard: flags-single
Allocated memory per operation (estimated) 14.23 KiB/op 14.19 KiB/op 0.3% less memory Not flagged
Evaluate a rollout flag
Shard: flags-single
Time per operation 39.57 µs/op 39.38 µs/op 0.5% less time Not flagged
Evaluate a rollout flag
Shard: flags-single
Process CPU time per operation 45.37 µs/op 44.89 µs/op 1.1% less time Not flagged
Evaluate a multivariate flag
Shard: flags-single
Allocated memory per operation (estimated) 17.43 KiB/op 17.52 KiB/op 0.5% more memory Not flagged
Evaluate a multivariate flag
Shard: flags-single
Time per operation 50.48 µs/op 51.02 µs/op 1.1% more time Not flagged
Evaluate a multivariate flag
Shard: flags-single
Process CPU time per operation 56.09 µs/op 56.36 µs/op 0.5% more time Not flagged

Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals.

Each shard uses its own runner; compare Before PR against With PR within a row, not across shards.

Compared e741866c7295976619401d788f2542e332baac0d → 4cf1529b685f248531057e834314f9ce5fdd0625.

Full report and diagnostics

102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in comparison.json, including per-runner environments, resource limits, measurement methods, samples and checkpoints.

Silthus and others added 2 commits November 13, 2026 05:35
…ries safe

- Refuse a message when a stream plugin is registered, since it changes MIME that PostHog doesn't send.
- Refuse headers on the html and text parts.
- Check the envelope only when the message sets its own, so a message without from that has a reply-to sends.
- Say a network error or an in-flight key is retryable only when the message has an idempotency key.
- Give data URL images stable content IDs, so a retry with the same key replays.
- Keep the read deadline referenced, so a script waits for the send to fail.

Ticket: PostHog/michaelr-context#41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Silthus

Silthus commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author

Note

🤖 Claude Opus 5.5 responding on behalf of Michael

Decisions from review rounds 1 (fixed in 5eef616) and 2 (fixed in c9a28bd), and the final reads (fixed in 38baa70 and 4cf1529):

  • 🤖 What does a registered stream plugin do? The message is refused as unsupported_option, because a stream plugin changes MIME that PostHog never sends.
  • 🤖 When is a failed send retryable? Only when the message has posthog.idempotency_key and the SDK would retry the failure. A message without a key is never retryable, because the SDK generates a new key for each send and an earlier attempt may have queued it. That includes a network error during an attachment upload, which the transport can't tell apart from one on the send.
  • 🤖 Is the 60-second read deadline configurable? No. The transport docs name it and its ETIMEDOUT.
  • 🤖 How does a retry of a message with data URL images replay? The content IDs Nodemailer generates for them are renumbered in order, so the same message maps to the same send. The renumbering skips any content ID the message sets itself, and changes only whole cid: references, so a longer content ID that starts with a generated one keeps its name.
  • 🤖 Does the transport undo the data URL images Nodemailer adds to a reused attachments array? No. Nodemailer pushes them into the caller's own array, so SMTP resends them on such a retry too; through PostHog the retry fails visibly with idempotency_key_reused and sends nothing twice.
  • 🤖 Does the transport check the size of attachments while reading them? No. It reads the message whole through normalize(), like Nodemailer's own JSON and SES transports, and the SDK refuses an oversized message after the read and before any request.
  • 🤖 Does the transport cancel Nodemailer's reads after ETIMEDOUT? Only through Nodemailer. Its Mailer closes the message's streams when a transport fails, and its fetch ends a URL within its own time and size limits. The file and URL streams are opened inside Nodemailer's content resolution, which the transport can't reach without reimplementing normalize() and its file and URL access settings.
  • 🤖 Does the transport use Nodemailer's own Transport and MailMessage types? No. It types only the slice it reads, so its declarations don't depend on how a Nodemailer version lays out its types.

…ata URL content IDs apart

A message without posthog.idempotency_key is not retryable on any failure,
since an earlier attempt of the send may have queued it. Renumbered data URL
content IDs skip any content ID the message sets itself. The process test waits
for the send to start before it checks the script stays alive.

Refs PostHog/michaelr-context#41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Silthus and others added 2 commits November 13, 2026 07:53
A longer content ID that starts with Nodemailer's generated one kept a
rewritten prefix in the HTML and lost its image.

Refs PostHog/michaelr-context#41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A srcset comma or an encoded quote in a CSS url left the reference on the
old content ID, so the renamed image broke.

Refs PostHog/michaelr-context#41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Silthus Silthus closed this Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant